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Introduction | 


The TDL 280 Relocating/Linking Assembler is the symbolic . 
assembly program for the 280. It is a two-pass assembler 
(requiring the source program to be read twice to complete 
the assembly process) designed -to run under the TDL system 
monitor. It 1s therefore device independent, allowing 
complete user flexibility in the selection of standard input 
and output device options. _ 
| The assembler performs many functions, making machine 

language programming eaSier, faster, and more efficient. 
Basically, the assembler processes the 2Z80 programmer's 
source program statements by translating mnemonic operation 
codes to the binary codes needed.in machine instructions, 
relating symbols to numeric values, aSSigning relocatable or. 
absolute memory addresses for program instructions and data, 
and preparing an output listing of the program which 
includes any errors encountered during the assembly. 

The TDL Z80 Assembler also contains a powerful macro . 
capability which allows’ the programmer to create new 
language elements, thus expanding and adapting the assembler. 
to perform Specialized functions for each: programming. job.. . 

In addition, the TDL Assembler: provides the facilities 
reguired to specify program module linkages, allowing the 
TDL Linkage Editor to link independently assembled program 

modules together into a Single executable program. This. 
allows for the modular and systematic development of large 
programs, and for easy sharing of common program modules 
among different programs. | ; | | 


Statements 


with the aid of a text editing program. A program consists 


of a Sequence of statements in the assembly language. Each _ 
Statement is normally written on one line, and terminated by . 


a carriage return/line feed sequence. TDL assembler ~ 


Statements are free-format. This means that. the various. . 


Statement elements are not placed at a specific numbered 
column on the line. _ 


There are four elements in an assembler statement (three ~ 


of which are optional), separated from each other by 
specific characters. These elements are identified by their 
order of appearance in the statement, and by the separating 
(or delimiting) character which follows or precedes the © 
elements. 3 
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Statements are written in the geferal form: 
label: Operator operand,operand scomment <CR-LF> 


The assembler converts statements written in this form into 
the binary machine instructions. 


“Instruction Formats 


: ED CED CEP CR CD CED aE CP EEF FOS COD 2 CP GP OF 28*® CD aD ae 


The 280 uses a variable length instruction format. A 


“ given machine instruction may be one, two, three, or four 


bytes long depending on the specific machine code and on the 
addressing mode specified. The TDL assembler automatically 
produces the correct mumber of machine code bytes for the 


a particular operation specified. Appendix A specifies the 


various machine code mnemonics accepted by the assembler and 
-'. the format of the operands Bequireds | 


a 


Statement Pormae. 


As previously described, assembler statements consist of 
a combination of a label, an operator, one or more operands, ~ 
and a comment; the particular combination depends on the 
statement usage and operator requirements. 

The assembler interprets and processes these statements, 
generating one or more binary instructions or data bytes, or 
performing some assembly control process. A statement must 
contain at least one of these elements, and may contain all 
four. Some statements have no operands, while others may 
have many. | Sa eS 

Statement labels, operators, . and operands may be 
represented numerically or symbolically. The assembler 
interprets all symbols and replaces them with a numeric 
(binary) value. 3 


The programmer may create symbols to use as statement 
labels, aS operators, and as operands. A symbol may consist 
of any combination of from one to six characters from the 
following set: a , ~ 


The 26 letters: A-Z 
Ten digits: 0-9 
Three special characters: 
$ (Dollar Sign) 
% (Percent) 
- (Period) 7 
| | ee 
These characters constitute the Radix-40 character set (so 
named because it contains only 40 characters). Any 
Statement character which is not in the Radix-40 set is | 
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treated as a symbol delimiter wher encountered by the 
assembler. | | | 

The first character of a symbol: must not’ be numeric. 
Symbols may also not contain embedded spaces. A symbol may 
contain more than six characters, Rhy ONY the first six are 
used by the assembler. 

The TDL assembler will accept programs written uSing 
both upper and lower case letters and symbols. Lower case 
letters are treated aS upper caSe in symbols. Additional 
special characters and lower case letters elsewhere are 
taken unchanged. | | : 


Labels 


A label is the symbolic name created by the programmer 
to identify a statement. If present, the label is written 
aS the first item in a statement, .and 1S terminated by a 
colon (:). A statement may contain . more than one label, in 
which case all identify the same statement. Each label must 
be followed by a colon, however. A Statement may consist of 
just a label (or labels), in which case the label(s) 
identifies the following statement. 

-When a symbol is used as a label, it specifies a 
symbolic address. Such symbols are said to be defined (have 
a value). A defined symbol can reference an instruction or 
data byte at any point in the program. 

A label can be defined with only one value. If an 
attempt is made to redefine a label with a different value, 
the second value is ignored, and an error is indicated. 

The following are legal labels: — 


SSUM: 

ABC: 

B123: — 

WHERE $s: 

The following are illegal: 


30QRT: (First character must not be a digit) 


AB CD: (Cannot contain embedded space) 

| If too many characters are used in a label, only the 
first six are used. For example the label ZYXwWVUTSR: is 
recognized by the assembler to be the same as ZYXWVUABC:. 


Operators 

An operator may be one of the mnemonic machine 
instruction codes, a pseudo-operation code which directs the 
assembly process, or a user defined code (either pseudo-op 
Or macro). The assembler pseudo-op codeS are described in 
Chapter 3 and summarized in Appendix B. 


' 
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| The operator element of a statement is terminated by any | 
character not in the Radix-40 set (uSually a space or a. 
tab). If a statement has no label, the operator must appear 
first in the Statement. 

A symbol used aS an operator must be predefined by the 
assembler or the programmer before its. firSt appearance as 
an operator ina statement. 


Operands 

Operands are usually the symbolic addresses of the data 
to be accessed when an instruction is executed, the names of 
processor registers to be used in the operation, or the 
input data or arguments to a pseudo-op Or macro instruction. 
In each case, the precise interpretation of the operand(s) 
is dependent on the specific statement operator being 
processed. Operands are separated . by commas, and are 
terminated by a semicolon (7) or .a, carriage return/line 
feed. | 

Symbols used aS operands must ages a value predefined by 
the assembler or defined by the programmer. These may be 
symbolic references to previously defined labels where the 
arguments used by this instruction are to be found, or the 
symbols may represent constant values or character strings. 


7 


Comments 

Tne programmer may add a comment to a statement by 
preceding it with a semicolon (3). Comments are ignored by 
the assembler but are useful for documentation and later 
program debugging. The comment is terminated by the 
carriage return/line feed at the end of the statement. In 
certain cases (e.g. conditional’ assembly and macro 
Gefinitions), the use of the left and right Square brackets 
({]) should be avoided in a comment as it could affect the 
assembly vorocess. | : 

An assembler statement may consist of just a comment, 
but each such statement must. begin with a semicolon. 


Statement Processing 

The assembler maintains several internal symbol tables 
for recording the names and values of symbols used during 
the assembly. These tables are: aut 


1. Macro Table - This table contains all macros. It is 
- initially empty, and grows as ‘the programmer defines 
macros. 


.- at = : : 
2. Op-Code Table - This eabie contains all of the machine 
operation mnemonics (op~codes), the assembler 
pseudo-operations (pseudo-ops), and user defined 
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operators (.OPSYNs). It initially contains the basic 
op-codes and pseudo-ops, and grows as. the programmer - 
provides additional definitions. | oe 


3. Symbol Table - This “table contains all 
programmer-defined symbols other than those described 
above. It initially contains the Standard register 
names, and then grows as new symbols are defined. 

Internally, all of these tables occupy the same space, so 

that all of the available space can be used as required. 

Order of Symbol Evaluation i 


The following table shows the order in which the . 
assembler searches the tables for a he eeee appear ing in each 
of the statement fields: | 


Label Field: : 
Ey Symbol followed by a colon. If no colon is found, 
no label is present. 


Operator Field: 
Li Macro 
ee Machine operator 
3% Assembler operator 
4 Symbol 


Operand Field: 
de Number 
Laz Macro 
36 Symbol 
4 Machine operator 


Because of the different table searching orders for each 
field, the same symbol could be used aS a label, an_ 
operator, and a macro, with no ambiguity. | 


Programmer~-Defined Symbols 

There are two types of programmer~defined symbols: | 
labels and assignments. As previously described, labels are 
generated by entering a symbol followed by a colon (e.g. 
LABEL:). Symbols used as labels cannot be redefined with a. 
different value once they have been defined. The value of a. 
label is the value of the location counter at the time the 
label is defined. 3 

Assignments are used to represent, symbolically, — 
numbers, bit patterns, or cl®aracter Strings. Assignments 
Simplify the program development task by allowing a single 
source program modification (the assignment statement) to 
change all uses of that number or bit pattern throughout the © 
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‘program. Symbols given values in an assignment statement - 
may have new values assigned in subsequent statements. The 
current value of an assigned symbol is the last one given to. 
it. 7 

A symbol may be entered into the symbol table with its 
assigned value by using a direct assignment statement of the 
forms: 


symbol = value {; or CR-LF} 


where the value may be any valid numeric value or 
expression. 
The value assigned to the symbol may subsequently be 
changed by another direct assignment statement. 
The porTenang are valid assignment statements: 


VALUE] = 23 : 
SIZE = 4*36 | a 
ZETA SIZE | — 


| If it is desired to fix the value assigned to a symbol] 
so that 1t cannot subsequently be redefined, the direct 
fixed assignment Statement should be used. This statement 
1S the same as the direct assignment statement except that 
the symbol is followed by two equal. signs instead of one. 
For example: | : 


FIXED == 46 
NEWVAL == SIZE 


Assembly-Time Assignments 

It is often desirable to defer the assignment of a value 
to a symbol until the assembly is actually underway (i.e. 
not specify the value as part of the Source program). This 
is especially useful in setting. program origin, buffer 
sizes, and in specifying parameter values which will be use@ 
to control conditional assembly pseudo-~ops. 

The TDL Assembler provides the ability to specify 
symbols with values to be determined at assembly time, and 
the mechanism by which the values may be interactively 
defined. To specify an assembiy~-time assignment, the 
following format 1S used: YA | | 


symbol =\ [dtextd] 


where the dtextd in brackets indicates the optional 
specification of a message to be output on the console 
device at assembly time befor& requesting the symbol's 
value. The d represents a text delimiter, and may be any 
character (other than a Space or tab) which is not contained 


in the ‘text itself. The text may contain. Carriage’ . 
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return/line feed sequences, which would result in a 
multi-line message on the console. ~™ | 
After the optional message is output on the console, a. 
colon (:) is output to indicates that the assembler is © 
waiting for the desired value to be entered. The value 
which is to be asSigned to the symbol is then input on the 
console device and the assembly continues with the symbol . 
having the specified value. This interaction only occurs 
during the first assembly pass. The symbol's value remains 
unchanged during subsequent passes. 

Only numeric values may be entered through the console 
in this fashion. The number which is input must conform to 
the same rules aS any other number used in the assembly 
source program, and may be followed by an. optional radix 
modifier (See the section on Numbers below). The number is 
assumed to be decimal unless followed by a radix modifier. | 

The value being input is not processed until a carriage | 
return is entered. Any mistyped character may be deleted by 
the use of the DELETE (or RUBOUT) key (which will echo the 
 Geleted character), and the entire: number may be deleted by 
entering CTL-U (Simultaneous use of the CTRL and the U key). 
Any character which is input but is not valid as part of a 
number will not be echoed and will be ignored. 

The following are examples of assembly-time assignment 
statements: 


BUFSIZ =\ "BUFFER SIZE (50 TO 500 CHARACTERS)" 
DISK =\ "VERSION (O0-PAPER TAPE 1-DISK)" 


Assembly-time assignment statements are similar to 
direct fixed assignments (==) in not allowing the symbol to 
be redefined elsewhere in the program. 


Local and Global Symbols 

When assembling a large program, it 1S sometimes 
difficult to keep track of the symbols used for local data. 
references and branching. To facilitate modular 
programming, the TDL assembler provides for both global and 


local symbols within a single program. All symbols which _ 
start with two periods are defined as being local, and all . 


Other symbols are global. For example, the following are 


valic local symbols: 


_ ABCD: 
~- 1234: 


A particular occurrence of a local symbol is only defined 
within the boundaries of its eaclosing global symbols. For 
example, in the following sequence. of label definitions, the. 
symbol ..SYMl is only defined (and can only be referenced) 
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the definition of GLOBl and 


GLOB2: 
GLOB1: i 7 
..SYM1: 
GLOB2: : 
This localization of., symbol definitions allows the same 
symbol to be used unambiguously more than once in the 
program. It also simplifies program understandability by 
immediately differentiating between local and global 
symbols. 7 fg | 

In addition to labels, any other programmer-defined 


symbol may be specified as 
manner. Because of the = loc 
do not appear in the symbol 
table optionally punched on 
External, Internal, 

Programmer-defined symbc 
internal, and entry point 
appearance as labels or in a 

Symbols which fall inte 
different from other symbols 
be referenced by other, 
modules. The manner in whic 
they are located: 
Or in the program in which ¢ 
defined elsewhere. 

If the symbol appears 
defined, 1t must be declar 
programs by the use of the 
through the use of 


"s\:" in their definit: 


 Gelimiters are exactly equiv | 


INTERN symbol 


symbol <delimiter without co. 


In each case, the delimiter 


operator (i, =, ==, 


If the symbol is locatec 


reference to a symbol define: 
use of the 
symbol 
to the 


declared as external by the 
through the use of the "#" 
symbol modifier is appended 


acal (e.g. 
l usage of 
table listing 

ye object tape. 


and Entr« 


in the prc. 


the de 


—\) wit. 
to indicate an internal symb 


macros) in the same. 
these symbols, they 
or in the symbol 


Symbols . 


may also be used as external, 
ymbols in addition to their 
ignment statements. | 
ne of these three groups are 
1. the program because they can 
sparately assembled, program 
chey are used depends on where 
am in which they are defined, 
y are a reference to a symbol 


which 1t is 
to other 
-ENTRY, or 


a program in 
as being available 
sudo-ops .INTERN or 


miters sey a3", “s=3", Or 


statements. These 


Special 
ant to the sequence: 


sn (3:)> 


is the normal symbol definition 
an additional colon (:) added 
1 definition. 


in a program in which it is a 
in gnother program, it must be 
-EXTERN pseudo-op, or 
modifier. This special 

end of 


any symbol to. ... 
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‘declare it external. For example, the statement: 
LXI ,SYMBOL# 
. is exactly equivalent to: 


~EXTERNAL SYMBOL 
LXI H,SYMBOL 


Numbers 

Numbers- used in a program are interpreted by the 
assembler according to a radix (number base) specified by | 
the programmer, where the radix may be 2 (binary), 8 
(octal), 10 (decimal), or 16 (hexadecimal). The programmer 
uses the .RADIX pseudo-op to set the radix for all numbers | 
which follow. If the .RADIX statement iS not used, the 
assembler assumes a radix of 10 (decimal). OO 

The radix may be changed for a Single number by 
appending a radix modifier to the end of the number. These 
modifiers are B for binary, O .or Q for octal, Dor. 
(period) for decimal, and H for hexadecimal. To specify the 
hexadecimal digits, the letters A through F are used for the. 
values 10 through 15 decimal. All numbers, however, must 
begin with a numeral. For example, the following are valid 
numbers: 


10 10 in current radix 

10. 10 decimal | 

10B. 10 binary (2 decimal) _ 

OF FH FF hexadecimal (255 decimal) 


The following are invalid numbers: 


14B 4 is not a binary digit | 
FFH the number must start with a numeral 


Arithmetic and Logical Operations 
Numbers and defined symbols may be combined ‘using ~ | 
arithmetic and logical operators. The following operators 


ae ewe ee ee we 


Add (or unary plus) © 

Subtract (or unary minus) 

Multiply , ; 

Integer division (remainder discarded) 

Integer remainder (quotient discarded) 

Logical AND | a | 

Logical inclusive OR ss 

Logical exclusive OR (or unary radix change) 
» Logical unary NOT | 


rem MON * | + 
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<* Left binary shift 
> Right binary shift 


The assembler computes the 16-bit value of a series of 

numbers and defined symbols connected by these operators. 
All results are truncated to the left, if necessary. Two's 
complement arithmetic is used, with the meaning of the Sign 
bit (the most significant bit) being left to the programmer. 
This means that a numeric value may. be either between 0 and 
65,535 or between -32,768 and 32,767, depending on whether 
it 1S Signed or unsigned. 

These combinations of number and defined symbols with 
arithmetic and logical operators .are called expressions. 
When evaluating an expression, the assembler performs the 
specified operations in a particular order, as follows: 


1. Unary minus or plus ( +) 

2. Unary radix change ("“B “O “Q “D “H) 
3. Left and right binary shift (< >)- 
4. Logical operators (& ! ~ #) | 
5. Multiply/Divide (* /) 
6. Remainder (@) 
7. Add/Subtract (+ -) 


Within each of the above groups, the operations are 
performed from left to right. For example, in the 
expression: , | 


~ALPHA+3*BETA/DELTA&~H55 


the unary minus of ALPHA is’ done first, then DELTA is ANDed 
with a hexadecimal 55, then BETA is multiplied by 3, the 
result of which is divided by the result of the AND, and 
finally, that result is added to the negated ALPHA. 

To change the order in which the operations are 
performed, parentheses may be used to delimit expressions 
and to specify the desired order. of computation. Each 
expression within parentheses is considered to be a Single 
numeric value, and 1S completely evaluated before it is used 
to compute any further values. For example, in the > 
expression: Z 


4* (ALPHA+BETA) 


the addition of ALPHA to BETA is peformed before the 
multiplication. | 


Radix Change Operator 

CR GER GD GOP aE amb em CER CD CER O88 eee Oe Ee ee oo are ee anh 3 : . 

| The radix change operator is used to temporarily change 
the radix in which a following number or expression is to be 
interpreted. It is written as an up-arrow (°") followed by 
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“the radix modifier of the desired* radix. These modifiers 
are the same as those used to specify the radix of a single 
number (B-binary, O Or QO-octal, D-decimal, and 
H-hexadecimal). The radix. change only affects the |' 
immediately following number or parenthesized numeric 
expression. For example, all of the following are valid 
representations of the decimal number 33: 


33.; 

33D 

“D33 

“D(10*3+3) 

“Dp (1O0*THREE+THREE) 
“D10*"D3+°D3 


but the following is not a representation of decimal 33 if 
the prevailing radix 1S not decimal: | 


“p3*10+3 


because the radix change only affects the value immediately. 
following it, in this case 3. 7 | 


Binary Shifting 

The binary shift operators (< left, > right) are used to 
logically shift a 16-bit value t6 the left or right. The 
number of places to be shifted is specified by the value 
following the shift operator. If that value is negative, 
the direction of the shift is reversed. For example, all of. 
the following expressions have a value of 4 decimal: 


8>1 
1<2 
2>-1 


One-byte Values 

All of the above discussion has been based on the - 
computation of l6—-bit (two 7. valves. Many of” 
the 280 operations require an 8-bit (one byte) value. Since 
all computations are done as a 16-bit value, an operation 
calling for only eight bits will discard the high order 
eight bits (the most significant byte) of the value. If the | 
byte discarded is not either zero or minus’ one (all one 
bits), a warning will be given on: the assembly pecans 


Character Values 
i hed ie ee nea ci ; 

To generate a binary value eguivalent to the ASCII 
representation of a character string, the single ('") or 


double (") quotation mark is used. The character string is _ 
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; | “ : . od 
‘enclosed ina vair of the quotation marks. For example, all> 
of the following are valid character values: 


ane | 
'B @ Tee 
"aR 
‘CD ¢ 


Note that whichever quotation mark-is used to initiate the 
character string it must also be used to terminate it. If 
the string is longer than two bytes, it 1s truncated to the 
left. Each 77-bit ASCII character™“:is stored in an 8-bit 
byte, with the high-order bit set to zero. 

A character string of this type may be used wherever a 
numeric value is allowed. | 

A single quote may be used inside a string delimited by 
double quotes, and vice-versa. If it 1s necessary to uSe a 
Single quote within a string delimited by single quotes, two 
single quotes must be used. The sdme is true for a double 
guote in a string delimited by sQubee ae ooeee 


Location Counter Reference 

The location counter may be referenced aS a numeric 
l6-bit value by the use of the symbol . (period). The value 
represented by . is always the location counter value at the 
Start of the current assembly language statement. For 
example: : - 


IMP . 


is an effective error trap, jumping.‘to itself continuously. 
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Addressing and Relocation 


Ge ws Ee aE Ge cee cD ee GP we PE waa aE oe ae ED Cn a cD a oD ee aD 


As source Statements are processed by the assembler, 
consecutive memory addresses are assigned to the instruction 
and data bytes of the object program. This is done by 
incrementing an internal program counter each time a memory 
byte iS assigned. Some statements may increment this 
internal counter by only one, while others could increase it > 
by a large amount. Certain pseudo-ops and direct assignment 
Statements have no effect on the counter at all. | 

In the program listing generated by the assembler, the > 
address assigned to every statement is shown. . 
Relocation 

The TDL Z80 Assembler will create a relocatable object — 
program. This program may be loaded into any part of memory 
as a function of what has been previously loaded. To 
accomplish this, certain 16-bit values which represent 
addresses within the program must have a relocation constant 
added to them. This relocation constant, added when the 
program is loaded into memory, is the difference between the 
memory location an instruction (or piece of data) is 
actually loaded into, and the location it was assembled at. 
If an instruction had been assembled at location 100 
(decimal), and was loaded into location 1100 (decimal), then 
the relocation constant would be 1000 (decimal). 
| Not all 16-bit quantities must be modified by the 
relocation constant. For example, the instructions: 


LXI H,OOFFH 


references a l6-bit quantity (OOFFH) which does not need 
relocation. However, the set of instructions: 


32 DONE ‘a 


DONE: 


does reference a 16-bit quantity (the address of DONE) which 
must be relocated, since the physical location of DONE 
changes depending on where tsae program is loaded into 
memory. . 

To accomplish this relocation, the 16-bit value forming 
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an address reference. iS marked by the assembler for later’ 
modification by the loader or linkage editor. Whether a 
particular 16-bit value is. so marked depends on the 
evaluation of the arithmetic expression from which it is 
obtained. A constant value (integer) is absolute (not 
relocatable), and never modified. - Point references (.) are 
relocatable (assuming relocatable code is being generated) ,’ 
and are always modified by the loader or linkage editor. 
Symbolic references may be either absolute or relocatable. 
If a symbol is defined by a direct assignment statement, 
it may be absolute or relocatable depending on the 
expression following the equal sign (=). If the symbol is a 
label (and relocatable code is being generated) then it is 
relocatable. - 
| To evaluate the relocatabllity of an expression, 
consider what happens at load or linkage edit time. A 
relocation constant, r, must be added to each relocatable 
element, and the expression evaluated. For example, in the 
expression: | 


% = Y+2*X-3*W+v 


where V, W, X, and Y are relocatable. Assume that r is the 
relocation constant. Adding this constant to each 
relocatable term, the expression becomes: 


%. 


Z(r) = (Y+r)+2* (X+r)—-3* (W+r)+(Vtr) = 
By rearranging the expression, the following is obtained: 
Z(cr) = Y+2*X-3*W+V + 5 


This expression is suitable for relocation because it 
contains only a Single addition of the relocation constant 
r. In general, if the expression can be rearranged to 
result in the addition of either of the following, it is 
legal: : 


O*r absolute expression 
LAE relocatable expression 


If the rearrangement results in the following, it is 
lllegal: 


n*r where n is not O or l 


Also, if the expression involves r to any power other than 
1, 1t 18 illegal. This leads to the following rules: : 


1. Only two values of relocatability for a complete 
expression are allowed (ie. n*r where n = 0 or 1). 
2. Division by a relocatable value is illegal. | 
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. 3. Two relocatable values may not.wbe multiplied together. 
4. Relocatable valueS may not be combined BY logical 


operators. 
S« A relocatable value may not be cca ena cesd: 


If any of these rules is broken, | the expression is illegal 
and an error message 1S given. 
If X, Y¥, and Z are relocatable symbols, then: 


X+Y—Z is relocatable , 
X~Z 1s absolute 

X+7 at 1s relocatable 

3*X-Y-Z 1s relocatable 


4&X-Z 1s illegal 


Only 16-bit quantities may be relocated. All 8-bit. 
values must be absolute or an error will be given. | | 
Relocation Bases _ 

One of the unique capabilities of the TDL 280 Assembler 
is its ability to handle symbolic references to Separately 
located areas of memory, where the mapping of symbols to 
physical addresseS occurs at linkage edit time. The 
symbolic names for independently located memory areas are 
called "relocation bases". These relocation bases may 
represent ROM vs. RAM, shared COMMON areas, Special memory 
areas such as video refresh, memory mapped I/O, etc. Within 
each subprogram, each of these memory areas 1S referenced by 
a unique name, with the actual allocation deferred to the 
link edit and load process. All memory references within 
the assembled program are relative to one of these 
relocation bases. 

As each relocation base 1s assigned a name in the 
program (through the use of the .EXTERN pseudo-op), it is 
implicitly assigned a Sequential identifying number. This 
number appears in the listing .-as part of any address 
relative to that base. 


Four of these relocation bases (0-3) have predefined .— 
names and meanings, and are treated differently at linkage: . 


edit time than the remainder of the bases. Base 0 
represents absolute memory locations (i.e. it always has the 
value of 0). Base l has the name .PROG. and represents the 
program area (maybe PROM or ROM). Most program code (and 
Gata 1n non-rommed programs) iS generated relative to this 
relocation base. Base 2 has the . name .DATA. and represents. 
the local data area for each module. Most local data is 
Gefined relative to this base. Base 3 has the name .BLNK. 
and represents the global "blank common". This relocation 
base is always assigned the v@lue of the first free byte in 
memory after the local data storage (.DATA.) and other data 
relocation segments by the linkage editor. Because it is 
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always. the last allocated, modules referencing this area can . 


be included in any order, regardless of the amount of the 
area they use. : A 

Relocation segments relative to bases 1 and 2 (.PROG. 
and .DATA.) are always allocated additively (i.e. after each 
module is allocated, the value of the relocation base is 
increased by the size of the segment). . All other relocation 
bases are normally assumed to have constant values during 
the allocation process (usually assigned by the linkage 
editor). 

Each symbol defined during the assembly has a relocation 
base associated with it. There are no limitations on 
inter-base references (i.e. code relative to °.PROG. can 
freely reference data relative to .DATA.). Expressions 
containing symbols must evaluate to avalue relative toa 
Single relocation base, but may contain references’ to 
multiple relocation bases. All relocation base references 
except for the final result must be-part of sub-expressions 
which evaluate to absolute values. For example, if T and U 
are symbols relative to base l, V and W relative to base 2, 
and X and Y relative to base 3, then’the following are valid 
expressions: | 7 


T+ (V-W) (note the parentheses to make V—-W 
a subexpression) 

X+3 | 

T-— (V-W) *0+(X-Y) 

and the following are invalid: 


T+U (within a relocation base, the 


normal relocation rules apply) 
T+V—W (T+V is the first subexpression, 


and it is mixed relocation bases) 


It should be noted that conceptually, normal external 
symbols are simply relocation bases with a size of zero (0), 
and the assembler treats them that way. An asSignment of 
the form: i OU 


N==P+5 P 

where P 1S an external symbol, makes N a_ symbol whose 
address is relative to P, even though P has no size. Hence, 
expressions of the form: boa 7 


9* (P-N) 


where P and N have the same regocation base, are in fact 
valid. 


last .LOC, the statement: 
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Pseudo-Operations 


Pseudo-operations (pseudo-ops) are directions to the . 
assembler to perform certain operations for the programmer, 


‘aS opposed to machine operations which are instructions to 


the computer. Pseudo-ops perform such functions as listing 


control, data conversion, or storage allocation. 


Address Mode and Origin 

The TDL 280 Assembler normally assembles programs in 
relocatable mode, so that the resultant program can be 
loaded anywhere in memory for execution. Therefore, all 
programs are assembled assuming .their first byte 1s at > 
address zero (0), because they can be relocated anywhere. 
When desired, however, the assembler will generate absolute 
object code, either for the entire: program, or just selected 
portions. The assembler will also locate the assembled code 
at any address desired. The two pseudo-ops which control 
address mode, relocation base and address origin are .LOC 
and .RELOC. } 


_LOC n 


This statement sets the location counter to the value n, 
which may be any valid expression. If n is an absolute 
value, then the assembler will assign absolute addresses to 
all of the instructions and data which follow. If n is 
relocatable, then relocatable addresses will be assigned, 
relative to the relocation base of the expression. 

The program is assumed to Start with an implicit .LOC tc 
relocatable address zero (0) of the relocation base named 
-PROG. (the default relocation base for normal programs). 
A program can contain more. than one .LOC, each controls the 
assignment of addresses to the statements following it.. | 

To reset the program counter to its value prior to the ~ 


-) 


.RELOC 


1s used. This statement restores both the value, the 
relocation base and the addressing. mode which were in effect 
before the immediately preceding .LOC. If no .LOC has been 
Gone, then a .RELOC is equivalent to a: | 

.LOC 0 = 
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‘When in relocatable addressing mode, the assembler will 
determine whether each 16-bit value 1S absolute or 
relocatable as described in Chapter 2. | 


a ad 


Data Definition 

The TDL Z80 Assembler provides a number of different 
pseudo-ops for describing and entering data to be used by 
the program. 3 


-RADIX | | 

When the assembler encounters a number in a- 

statement, it converts it to -a 16-bit binary value 
according to the radix indicated by the programmer. The 
statement: 


-RADIX n 


where n is 2, 8, 10, or 16, sets’the radix to n for all 

numbers which follow, unless another .RADIX statement is 

encountered, or the radix is modified by the “r operator 

or a suff1x radix modifier. i 
The statement: 


~RADIX 10 


implicitly begins each assembly “program, setting the 
initial radix to decimal. | | 


sBYTE 
To enter one (or more) 8-bit (one byte) data values 
into the program, the statement: ” 


-BYTE n {, n...} 


where n iS any expression with .a valid 8-bit value is 
used. More than one byte can bé defined at a time by 
separating it from the preceding value with a comma.. 
All of the bytes defined in a single .BYTE statement are. 
assigned consecutive memory locations. For example: 


-BYTE 23,4* HOFF,BETA-ALPHA 
defines three Sequential bytes of data. 


-WORD ; _ | 
To enter a Il6-bit (two byte) value into the 
program, the statements: / 4 3 ; 
| u 
-WORD nn {, nn ...]} 
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where nn 1S any expression with a gaia 16-bit value, is 
used. Multiple 16-bit values may be defined with one 
-WORD statement by Separating each from the preceding 
one with a comma. — | ‘ _ e 

All 16-bit values defined by the .WORD pseudo-op 
are stored in standard Z80- word format, least 
Significant byte first. | 

For example, the following statement: 


-WORD ALPHA, 234*BETA, HOEEFF 


defines three Sequential 16-bit values, ora total of 
six bytes of data. *. 


-ASCII, .ASCIZ, and .ASCIS 3 | 
To enter strings of text characters into the 
vrogram, one of the statements: 


ASCII dtextd | {[n] | ste 
-ASCIZ dtextd | [n] fy 
-ASCIS dtextd | [n] 


is used. The d represents a text delimiter, and may be 
any character (other than space or tab) not contained in 
the text itself. Each character in the text 1s 
converted to its 7-bit ASCII representation (with the 
eighth bit zero), and stored in Sequential memory 


locations. When the Gelimiter character 1S again 
encountered, the text is considered terminated (the 
delimiter is not stored with the string). The delimited 


String may be followed by another delimiter, and another 
String, and this may be repeated as desired. 

If it is necessary to include values in the text 
String for which no character exists, then the second 
option shown above may be used. If in place of a string 
dGelimiter, the assembler finds a left Square bracket 
({), then the numeric expression enclosed within it and 
a matching right square bracket (}) 1S evaluated as an 
8-bit value and stored as the next byte of the string. 
These 8-bit values may be intermixed with delimited 
Strings aS reguired. | | 

It iS important to note .that tab, carriage return, 
and line feed are all jalid characters within a 
delimited text String. It is therefore possible that a 
-ASCIx statement will encompass more than one line in 
the source program. | | HO 

The difference between: the three pseudo-ops- 
Gescribed above is in’ their treatment of the last byte 
generated by the statement. The .ASCII statement just 
Stores the ‘byte. The .AxuCIZ Statement stores one 
additional byte after the last one, a null (zero) byte. 
to mark the end of the string in memory. The .ASCIS 
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“‘pseudo-op sets the high-order (eighth) bit of the last 
byte to one to flag the last byte... 

The following are all valid .ASCIx statements: 
-ASCII /This is a string/ — 
-ASCIZ /This is two/ ‘ strings in one place’ 
-ASCIS [HOD] [HOA] “Message on new line" 
ASCII \ | 
Message on new line\ | a? 


-RAD4O | | : 
The Radix-40 character set for symbols was chosen 
because it allows a six character: symbol to be stored in 
only four bytes of memory. To allow the program to 
define data bytes in this character set, the statement: 


~RAD40 symboll {, symbol2 ...} 
is used. The symbol must conform to all the rules 
specified for assembler symbols, and 1S converted into 
the Radix-40 nmotation and stored in four sequential 
bytes of memory. If multiple symbols are to be 
converted and stored, each must be separated fnOn the 
preceding one by a comma. 


Storage Allocation 


Oe. Gem aan GN em em@ wth GED eee ee aD ae ew OO cm en OF eam 


The TDL 280 Assembler allows the . programmer to reserve 
Single locations, or blocks of many locations, for use 


during the execution of the program. The two pseudo-ops- 


used for this purpose are .BLKB and .BLKW. The format of 
the statement using these pseudo-ops is: 


~BLKx n 


where n is the number of storage locations to be reserved. 
For the .BLKB pseudo-op, each storage location consists 


of one byte, so the above statement will reserve n. 
contiguous bytes of memory, Starting at the current location 


counter. The .BLKW pseudo-op uses a word (two bytes) as its 


storage unit, so the above statement would reserve n words, 


or two times n bytes of contiguous memory. 
For example, each of the following statements reserves 
24 (decimal) bytes of storage: 7 


-BLKB 24. . _ 
-BLKW ~D12 
-BLKB 2*12. 


TDL 280 Relocating/Linking cnuainde User's Manual Page 2] 
Chapter 3: Pseudo-Operations . 


-* Program. Termination | a 
Every program must be terminated by a .END pseudo-op. 
The format of this statement is: 


e-END Start 


where start is an optional starting address for the program. 
The starting address 1S normally only necessary for the main 
program. Subprograms, which are called from the main 
program, need no Starting address. 

When the assembler encounters the .END pseudo-op during 
pass 1 of the assembly, it returns to the initialization. 
point to await further instructions (see Appendix C). Ona 
listing pass, the .END pseudo-op initiates the printing of 
the symbol table (if not Suppressed by a prior .XSYM. 
pseudo-op). On a punching pass, ‘the ~.END pseudo-op punches 
the EOF record on the object tape... 7 | 


Subprogram Linkage 

Programs usually consist of a main program and numerous 
Subroutines which communicate with each other through 
parameter linkages and through reference to symbols defined 
elsewhere in the program. Since the TDL 280 Assembler 
provides the means for the variousS program components to be 
assembled separately from each other, the linkage editor 
(which finally puts the pieces together) must be able to 
identify those symbols which are references (or referenced) 
external to the current program. For a given subprogramn, 
these "linkage" symbols are either symbols defined 
internally which must be available to other programs to 
reference, or symbols used internally but defined externally | 
to the program. Symbols defined within the program but 
avallable to other Subprograms are called “internal” 
symbols. Symbols used internally ‘but defined elsewhere are 
called “external" symbols. 

To set up these linkages between Subprograms, ‘four 
pseudo-ops are provided: .IDENT, .EXTERN, .INTERN, and | 
eENTRY. | 8 

The .IDENT statement has the, format: 


~IDENT symbol 


where symbol is the relocatable module name. This name is 
used by the linkage editor to identify the module on memory > 
allocation maps, and to allow the selective loading of the 
module if it 1s part of a Subprogram library. If the .IDENT 
Statement does not appear in a,program, the name ".MAIN." is 
assumed. The .IDENT name appears at the top of every 
listing page, and 1s displayed on the console at the start 
of the second assembly pass of that module. S deere ac grdite 


, 
i 
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All three remaining statements Mave the same format: 


~-EXTERN symboll {, symbol2 ...} 


~INTERN symboll {, symbol2 ...} 


‘ —-e 


-ENTRY symboll {, symbol2 ...} _ 


where symboll is the symbol being declared as external, . 
internal, or as an entry point. Multiple symbols may be’ 
declared in the same statement by. Separating each from the 
preceding one with a comma. 


The .EXTERN statement identifies symbols which are 


“: defined elsewhere. External symbols must not be defined 


within the current subprogram. The external symbols may 
only be used as addresses, or in expressions that are to be 
used as addresses. External symbols may be used in the same _ 
manner aS any other relocatable symbol, with the following . 
restrictions: | | ; sO 


A 


2 


The use of more than one exte nal symbol in a single 
expresSion is illegal. Thus ae where X and Y are both 
external is illegal. 

Externals may only be additive. Therefore the following 
expressions are lllegal (where X is an external symbol): 


—X 
2*X 
SQR-X 
2*X—X 


Symbols declared as external by the .EXTERN pseudo-op 


may also be used as relocation bases. This is done by uSing 
an external symbol as the argument.to a .LOC pseudo-op. All 
memory allocated by the assembler after the .LOC will be 
addressed relative to the specified relocation base. The 
most common use of this capability 1s the declaration of 
COMMON blocks for the sharing of data between assembler and 
FORTRAN subprograms. All named COMMON blocks are in fact 
just different relocation bases. Symbols used as relocation 


bases have unigue values during the assembly of the program _ 


module. At any point in time, the current value of the 
relocation base symbol is the number of bytes which have 


been 


aliocated to that base so far. This means that 


subsequent .LOC pseudo-ops referencing the same external 
symbol will start the memory allocation at the next. 
available byte in that relocation base, not at relative © 
location zero (0)., 


There are three predefined relocation base symbols: 


-PROG., .~DATA. and .BLNK.. These relocation bases are used 
for the program code, separately located data (in a ROM/RAM 
environment), and blank (unnamed) common respectively. 


Ene current subprogram which are to be made accessible to . ._ 


The .INTERN pseudo-op identifies those symbols within 


i 


TDL 280 Relocating/Linking Assembler User's Manual Page 23 
Chapter 3: Pseudo-Operations | 


ca 
wo! ww 


‘other programs as external symbols» This statement has no 


effect on the assembly process for the current program, but 
merely records the name and value of the identified symbols 
on the object tape for later use by the linkage editor. An 
internal symbol must be defined within the current program 
as a label, or in a direct assignment statement. 
The .ENTRY pseudo-op functions identically to the 
-INTERN pseudo-op, with one addition. It is sometimes — 
desirable to put many subroutines with common usage into one 
"library", and to allow the linkage editor to select only 


those programs from the library which are called by the 


program being. linkage edited. 
The .ENTRY statement, in adaitién to functioning as a 
-INTERN statement, also flags the specified symbols as 
program entry points. If the subprogram is later put into a 
library, this will specify to the linkage editor that this | 
program is to be included only if one of its entry points is 
referenced aS an external symbol .by an already included 
program. ue | 
| Since these entry points are external to the program 
referencing them, they must be listed in a .EXTERN statement. 
in the calling program. 7 


Listing Control 

Program listings are printed on the list device during 
pass 2 and 4 (See Appendix C) of the assembly. The listing 
1S printed as the source program statementS are processed 


during the pass. The standard listing contains (from left 


to right): 


1. Error flags (if present). 

2. Location counter for the first byte generated by ‘this 
Statement. | 

3. Instruction or data in hexadecimal (maximum of five 
bytes per line printed). . 

4. Exact image of the input statement. 


The standard listing displays all 16-bit quantities in | 
16-bit (two byte), most significant byte first, format.- 
These quantities are properly reversed in the object code as 
required by the 280. A 16-bit relocatable address relative 


to the .PROG. relocation base is flagged with an apostrophe 


('), one relative to the .DATA. relocation base is flagged 
with an asterisk (*), and all others are followed by the 
assigned number of their relocation base. | 

Within a macro expansion, only the macro call and those 


statements which generate actual object code are poemal ey 


listed. 
If a single Statement generates more than the maximum of 
five bytes that can be listed on a Single line, the 


remaining bytes are properly generated, but not normally | 
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Listed. | “8 
A listing always begins at the top line of the page, and © 
60 lines are printed per page, with a two line margin at the 


top, and a two line margin at the bottom. A page is assumed | 


to be 72 (or 79) columns' wide (depending on the list device. 
selected - see Appendix C). Each page is numbered, and can 
have an optional title and sub-title. 

The standard listing options can be changed and expanded 
by the use of the following pseudo-operations: 


~PAGE | This statement causes the assembler to skip to 

> the top of the next page (by counting lines). 
A form feed character in the input text will 
have the same effect. 


.XLIST This statement causes the assembler to stop . 
| listing the assembled program at this point. 


-LIST This statement is normally used following a 
-XLIST to resume program listing. 


. LALL This statement causes the assembler to list 
everything which is processed. This includes 
all text, macro expansions, and all other 
Statements normally eGEE vere in the standard 
listing. 


. XALL This statement is eaaay used following a 
-LALL to resume the normal listing. 


-SALL This statement causes the Suppression of all 
macro expansions and. their text. It can be 
reset by a subseguent .LALL or .XALL. 


-XSYM This statement suppresses the symbol table 
listing normally performed upon encountering 
the .END statement. 


-LSYM Normally not used, this’ statement enables the _ 
listing of the symbol table previously ~ : 
Suppressed by the .XSYM pseudo-op. 


. LADDR This statement causes the assembler to list 
all 16-bit quantities in the same order it 
generates them in the object code (least 
Significant byte first). 


- XADDR Normally used following a .LADDR statement, 
| this statement resumes the normal listing of 
16-bit guantities in non-swapped format. 
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» LIMAGE 


~ XIMAGE 


-LCTL 


.XCTL 


.SLIST 


-RLIST 


Pseudo-Operations 


This statement causes ,the assembler to list 
every byte generated, even if more than one 
line (at five bytes per line) is required. In 
this mode, the assembler will attempt to split 


the input source statement to indicate which ° 


part of the statement. 1S generating which 
bytes. | | 


Normally used following a .LIMAGE statement, 
this statement resumes the normal listing of 
only five bytes of generated data per 
Statement. 


This statement causes all Subsequent listing 
control statements (e.g. .~.XLIST) to be listed 


themselves. Normally, no listing control 


statement is itself listed. The ,ACTE 
pseudo-op is used to reset this option. . 


Normally used following a .LCTL Statement, 
this statement resumes the default suppression 
of the listing of listing control statements. 


This statement causes the current listing 
control flags to be saved ona four element 
push-down stack. The current flag settings 
remain unchanged. These settings may later be 
restored with the. .RLIST pseudo-op. This 
pseudo-op may be followed on the same line 
with another listing control pseudo-op, which 
will take effect prior to the listing of the 
-OLIST statement. 


This statement restores the listing control 
flags from the top element of the .SLIST 
push-down stack. These new flags take effect 
with the statement following the ~.RLIST. 


-TITLE dtextd This statement defines the delimited | 
String text to be the title to be printed at -- 


the top of every page of the listing. The . 
text must be delimited in the same manner as 
in the .ASCII pseudo-op, and must be no longer 
than 72 characters. If the .TITLE pseudo op 
is the first statement on a vage, then the new. 
title will be printed at the top of that page. 


-SBTTL dtextd This statement Gefines the delimited 


String text to be the sub-title to be printed 
at the top of efery page of the listing. It 
follows the Same - rules as the .TITLE 
pseudo-op. 
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Se REMARK dtextd This statement inserts a remark into the 
listing. The delimited text can be any number 
of lines long, being terminated only by the 
matching delimiter. — | 

- PRNTX dtextd This statement, when encountered, causes 
the delimited text string to be typed on the 
console. This statement is frequently used to © 
print out conditicnal information, and to 
report the progress." through pass 1 on very 
long assemblies. 

Punch Control 

The TDL 280 Assembler normally produces an object tape 
in the TDL Standard Relocatable Format (See Appendix EE). 
However, the assembler can produce.an object tape compatible 
with the “INTEL Standard" hex tape... To control which format 
1s being produced, the two pseudo-ops .~.PREL and .PABS are 
used. The .PABS pseudo-op causes the assembler to produce 
an INTEL compatible tape for all .following generated code. | 
The .PREL causes the assembler to return to producing TDL 
Standard Object Tape. 

Every program starts with an implicit .PREL pseudo-op. 

In addition, the assembler can punch the output tape in 
both binary and ASCII. To control which type of output is 
being produced, the two pseudo-ops .PBIN and .PHEX are used. 

The .~.PBIN pseudo-op causes the assembler to produce a binary 

tape in the current format. The .~PHEX pseudo-op causes the 

output of an ASCII tape. Every program starts with an 
implicit .PHEX pseudo-op. 

To control the generation of linkable object modules, 
two pseudo-ops are provided. The. .~.LINK pseudo-op indicates 
that linkage information is to be included in =the object 
file produced. The -XLINK pseudo-op inhibits this 
information from being output. ey program Starts with an 
implicit .~XLINK pseudo-op. a 

The TDL 280 Assembler ppeuides one additional facility 
to assist the TDL 280 Debugging System. At the programmers 


a. 


option, the assembler will punch all of the global --. 


(non-local) symbols in the program module onto’ the end of 
the object tape. For each syinbol, the assembler also 
punches its relocation base and its value relative to that 
base. Two pseudo-ops are provided to control this symbol 
table punching. The .PSYM pseudo-op enables’ the punching, © 
and the .~.XPSYM pseudo-op disables it. The default is to not 
punch the symbol table (.XPSYM). 


o 
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Conditional Assembly 
Parts of a program may be assembled ona conditonal 

basis depending on the results of certain tests specified to -: 

the assembler through the use of the .IFx pseudo-op. 
The general form of the pseudo-op is: 


-IFx arg, [true text] ... {{false text] } 


where the text within the first sSguare brackets 1S assembled 
only if the specified test on the argument is TRUE, and the 
optional text within the second set of brackets 1s assembled 
if the condition is false. Any .number of spaces or blank . 
lines (or lines with only comments) may Separate the true 
and false texts. | 

The square brackets around the true text may be omitted | 
if there is no false text, and-the entire true text is _ 
contained on the same line as the .JFx pseudo-op. | 

The first set of conditions which can be tested are the © 
numeric value of the argument. These pseudo-ops are listed 
below: te, 


TRUE if n=0 or n=blank 


stPE Ny be<s] 

-IFN on,({...] TRUE if n<O or n>O 
sIFG Nylese] TRUE if n>0 

-1FGE n,[...] TRUE if n>O or n=0 
oe os Came ere (ere TRUE 1f£ n<OQ- 
-IFLE n,([...] TRUE if n<0O or n=0 


The following .IF pseudo-ops test for whether the 
assembler is processing pass 1 or not: 7 


leses) TRUE if it is ‘pass 1] 
eee | TRUE if it is not pass l 


The next set of conditionals tests for whether a symbol 
has been defined yet or not: ' | 


-IFDEF symbol,[...] TRUE if the symbol is defined . 
-IFNCEF symbol,[...] TRUE if the symbol is undefined 

The next set of .IF pseudo-ops tests to see whether its 
argument 1S blank or not. These pseudo-ops reguire that the 
argument be enclosed in Sguare brackets ([]). The format is 
as follows: | 


.IFB [...],{..-] TRUE if blank” . 
~-IFNB {...],[...] TRUE if not blank 


_ | 
The quantity enclosed in the brackets iS blank if it is 
empty, or consists only of spaces and tabs. Optionally, the 
argument being tested may be enclosed in paired delimiters 
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-in the Same manner as the .ASCIx pseudo-ops. If the first 
non~blank, non-tab, character after the pseudo-op is a left 
Square bracket ([), the bracket method is used, otherwise, 
the delimiter method. For example: OO 


glP Rf :3<é.07 ¢ laws 


The last pair of conditionals operate on character 
Strings. They take two arguments which are interpreted as 
¢7~bit ASCII character strings, . and make a character by 
character comparison of the two strings to determine if the 
condition is met. Each of the strings may either be 
enclosed in sguare brackets or delimited by a character, as 
in the .IFB/.IFNB pseudo-ops above. The same method need 
not be used for both strings. The format of these 
conditionals is as follows: | 


Toe 


SIP LDN ‘Perce Peed) e-feu c) TRUE if identical 
REDIF’ Dewa) Weel oclesed TRUE aif different 


The maximum length of the strings to be compared is 255. 
characters. In making the comparison, all trailing blanks 
and tabs are ignored in the two arguments. 


synonyms 

It sometimes becomes useful, for documentation or ease 
of programming, to define new names for already existing 
symbols. The TDL 280 Assembler has four pseudo-ops which 
allow the definition of synonyms for already defined 
symbols. The format of these pseudo-ops is: 


~-xxSYN symboll,symbol2 


The four pseudo-ops are .SYN, .OPSYN, .SYSYN, and .MASYN. 
The only difference between the four is that the latter 
three limit the type of symbol | for which the synonym is 
being defined. : 

The statement above defines the Second operand as being 


Synonymous with the first operand. In the case of the .SYN-- |. 


pseudo-op, the symbol tables are searched for the first 
operand in the order: programmer defined symbol, macro, 
operation. The ..QOPSYN pseudo-op limits the search to 
operations, the .SYSYN to programmer defined symbols, and 
the .MASYN to macros. The second operand 1s defined to be: 
identical to the first operand at the time the synonym is. 
defined. Later changes to the first operand will not affect 
the second. 
The following are valid Synonym definitions: 


-OPSYN .BYTE,DB 
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..SYSYN ALPHA,BETA | 2 


Object Machine Validation 


processor, it can obviously be used to generate object code 
for any of the 8080 compatible micro-processors. To _ 
facilitate the use of the assembler for this purpose, two 
additional pseudo-ops are available: .18080 and .280. 

The .18080 pseudo-op causes all Subsequent uses of 
machine operations which are unique to the 280 (and hence 
unavailable on the 8080) to be flagged with a Z warning — 
message. Such uses will be properly assembled however. 

The .280 pseudo-op (which is the default) disables the 
feature so that no further Z warnings will be given. | | 


4s 


i 
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Chapter 4 


Macros 


A common characteristic of assembly language programs is 
that many coding sequences are repeated over and over with 
only a change in one or two of the operands. It is 
convenient, therefore, to provide a mechanism by which the 
repeated Sequences can be generated by a Single statement. 
The TDL Z80 Assembler provides the capability to do so py 
allowing the repeated sequences to be written, with dummy 
values for the changed operands, as a macro. A Single 
Statement, referring to the macro by name and providing 
values for the dummy operands, can then generate the. 
repeated sequence. 


Macro Definition 


RSP ce COR eet em CER ak Oe Eh te CE ome ee com eae ao 


This 1s ffollowed by the symbolic name of the macro. The 
macro name must follow the rules for the construction of. 
symbols. The name may be followed by a list of dummy 
arguments enclosed in square brackets. The dummy arguments 
are separated by commas, and may be any symbol which is 
convenient. Following the macro ‘name and optional dummy 
arguments must be an equal Sign (=). The following are 
examples of the heading part of a macro definition: 


.DEFINE MACRO = 
.DEFINE MOVE[A,B] = 7 
.DEFINE BIGMAC [ARG1,ARG2,ARG3,%ARG5] = 


Following the macro definition header comes the body of 
the macro. It need not Start on the same line as the 
definition header. The body of the macro is delimited by a 
matched pair of left and right Square brackets ({]). For. 
example: 


-DEFINE MOVE [A,B]= 
[LDA A 
STA B] 


Macro Calls 

A macro may be called by any statement. A macro call 
consists of the macro name followed (optionally) by a list 
of arguments. The arguments are separated by commas, and 
may optionally be enclosed in Feft and right square brackets 
({]). If the brackets are used (the first non-blank/non-tab 
character after the macro name is a left square bracket), 
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a 
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.then the arguments are terminated by a right Square bracket. 
If there are n dummy arguments in the macro definition, then 
all arguments after the first n are ignored (although they 
do take space and time to process). -If the brackets are: 
omitted, the argument string ends..when a Carriage return or 
semicolon is encountered. 

The arguments must be written in the order in which they. 
are to be substituted for the dummy arguments. The first 
argument is substituted for each appearance of the first 
dummy argument, the second for the second, etc. The actual 
arguments are substituted as character strings for the dummy 
arguments, no evaluation of the arguments takes place until 
the macro is processed. es | 

Referring to the definition of MOVE above, the 
occurrence of the statement: . 


MOVE ALPHA,BETA 


will cause the substitution of ALPHA for A and BETA for B in 
the macro. | 

Statements which contain macro calls may be labelled and. 
have comments like any other statement. 

Macro arguments are terminated only by comma, carriage 
return, Semicolon, or’right Square bracket (when started by 
left sguare bracket). These characters may not be used in 
the arguments unless the argument is enclosed in 
parentheses. Each time an argument 1S passed to a macro, 
one set of matched parentheses 1S removed, but all of the 
characters within the parentheses are Substituted for the 
dummy argument in the macro. Note that spaces and tabs do 
not terminate arguments, but are considered to be part of 
them. : 

Macros do not need to have-arguments. The macro name 
(and arguments 1£ any) may appear anywhere ina Statement 
where a symbol would normally appear, and the text of the 
macro exactly replaces the macro name and itS arguments in 
that statement. am 


Comments 

Comments may be included within a macro definition. 
Storing the comments with the “macro (so that they will 
appear when the macro 1s expanded) takes space however. If 
the comment within the macro definition is preceded by two 
semicolons (instead of the normal one), the comment will be 
ignored during the definition of the macro, and will not be. 
stored as part of the definition. This will eliminate the 
appearance of the comment every time the macro expansion is 


listed, however. _ 
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Created Symbols | | - 

When a macro is called, it is often useful to generate 
symbols without explicitly stating them in the call. A good 
example of this is labels within the. macro body. It is 
usually not necessary to refer to these label externally to 
the macro expansion, therefore there 1S no reason why the 
programmer should be concerned as to what those labels are. 
The same with temporary data areas. To avoid conflicts, 
however, it is necessary that a different symbol be used 
each time the macro is called (even with local symbols, the 
macro could be called more than once between two global 
symbols). Created symbols are used for this purpose. 

Each time a macro that requires a created symbol is 
called, a symbol is generated znd inserted into the macro. 
These symbols are of the form ..nnnn (two periods followed 
by four digits). It should’ be noted that this makes these 
symbols local symbols (star. with ...two periods). The 
programmer is advised not to wu 2 symbals of this form. The 
four digits start at 0000 and are eer Cntee by one each 
time a symbol is created. 

A created symbol 1s specifiei in tne macro sePinveion by 
preceding a dummy argument by -~ percent sign (%). When the 
macro 1S called, all dummy argu: nts of the form %symbol are 
replaced by created symbols (- ch with a different one). 


If, however, the position of ne dummy argument in the 
argument list corresponds to an actual argument provided in 
the call, then the actual args nt is used in place of the 
created one. a ; | 

An actual argument can in act be empty (signified by 
two consecutive commas in the oirgument list). An argument 
of this kind (a “null"™ argument is considered to be defined 
aS having a value of the empt: string (no characters), and 
Will prevent the generation cc a created symbol for its 


corresponding dummy argument. 
For example: 


.DEFINE PRINT[A, %B]= 
{CALL LINPRT 

IMP $B 

.ASCIS \A\ 

$B: ) 


This macro printS a message on the printer. The first 
argument to the macro 1S the text string to be printed... 
LINPRT is aline printer routine. Labelling the location 
following the text 1s Ne eoeT because of the indeterminate 
length of the message. The us: of a created symbol here is 
useful since there would norma:iy be no reason to reference 
the label. Calling the macro by: . 
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PRINT This is the message _ 


o* 


would result in printing "This 1s the message” when the 
assembled macro was executed. If-it had been called: 


‘ ae 


PRINT This is the message,MAIN 


the message would have been printed, but control would he 
transferred to the label MAIN, which substituted for %B 
instead of a created symbol. 


Concatenation 


The apostrophe or single quote (') is defined within a 
macro definition as the concatenation operator. This allows 
a macro argument to be only part of a symbol or expression, 
with the character string which is substituted for the dumny 
argument being joined with other. character strings that are 
part of the macro definition to. .form a complete symbol or 
expression. This joining 15: called concatenation. 
Concatenation 1s performed by the assembler when an 
apostrophe is used between the strings to be joined (one or 
both of which must be a dummy macro argument). For example: 


.DEFINE BR[A,B])= 
[JR'A B] 


Gefines a conditional branch statement. When called, the 
argument A is appended to the JR to form a Single symbol. 
If the call were: 


BR Z2,LOOP 
then the generated code would be: 
JRZ LOOP 


Default Arguments 
Normally, missing arguments in a macro are replaced by _ 
nulls. For example, in the macro: , me 


-DEFINE BYTES {[A1,A2,A3,A4,A5,A6]= 


[.BYTE A1,A2,A3,A4,A5,A6] 


a call of BYTES[1,2] would generate an error because of the 
missing arguments to the pseudo-op .BYTE. —_ 

To remedy this, the assembler provides the programmer 
with the means to supply default arguments to be used when 
no argument 1S provided in the macro call. Default 
arguments are defined aS part of the macro definition by 
enclosing them in parentheses and inserting them immediately 
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: ® : of 
after the dummy argument to which they refer. To solve the 
above problem, the definition would be written as: 


.DEFINE BYTES [A1(0),A2(0) ,A3(0) ,A4(0) ,A5 (0) ,A6(0)]= 
[.BYTE Al,A2,A3,A4,A5,A5] 


which would always generate six bytes of data, regardless of 
how many arguments were provided in the call. 


ASCII Interpretation of Numeric Arguments . 

If the reverse slash (\) preceeds the first character of 
an argument in amacro call, the value of the expression 
Following the reverse Slash 1S converted to an ASCII string. 
This String is then used as the argument to the call. The 
value 1S considered to be a 16-bit positive value, and the 
conversion 1S done in the current radix. Leading zeros are 
suppressed unless the value is zero. i 

For example: 


A 5 
B 6 
MACRO \A+B, \A*B 


Wl 


is the same as: 
MACRO 1l, 30 
if the current radix is 10. 


Macro Expansion Termination 


RE EE ED ORE UNA SESS Ce EE eh asi ee 


sh CE eS Goth ake etki Dag ate mE 


Under normal conditions, a macro expansion terminates at 
the end of the macro definition. It is sometimes desirable 
to terminate the macro expansion prior to the end of the 
definition. This is usually done as part of some 
conditional assembly within the macro. A special pseudo-op 
is provided for this purpose: 


BALL 

When processed by the assembler, the .EXI pseudo-op 
immediately terminates the macro expansion, aoe as 1f£ the 
end of the macro had been encountered. Only the current 
expansion is terminated if multiple macro expansions are 
being nested. 7 


User Defined Macro Errors 

It is Sometimes desirable to have: a macro cause an 
assembly error. This might be done when invalid parameters 
are passed to the macro, or if parameters are missing. A 
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special pseudo-op is provided to. allow this: 


oh 


-ERROR dtextd 


This pseudo-op will cause an asterisk (*) to be listed as 
the error code, the error count:+ to be incremented by one, 
and the line to be listed aS anerror. The delimited text 
is treated exactly aS in a .REMARK pseudo-op, and can he 
used to provide information about the nature of the error. 


Nesting 

Macros may be nested. This means that macros may be both 
called and defined within other macros. A macro that is _ 
Gefined within another macro may not be called until the 
defining macro has been called. At that time, the new macro 
1S available to be called by any Statement. 

The only limit to how many levels deep macro calls and 
Gefinitions may be nested is the amount of memory avallable. 
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Appendix A 


Summary of Machine Operation Mnemonics 
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The following section presents a summary of the 280 
machine operations'9 and their assembler mnemonics. The 
appendix 1S arranged by. type of . instruction for ease of 
reference. For further information on the machine 


« Operations, refer to the "ZILOG Z80-CPU Technical Manual". 


To make the information presented more readily usable, a 
Shorthand notation 1s used for describing the assembler 
format of the ' instruction and its actual operation. All 
capital letters and special charcters in the mnemonic 
description are required. The lower case letters indicate a 
class of values which can be inserted in the instruction at 
that point. A Single lower case letter indicates an 8-bit 
gGuanity or register, while a double lower case letter 
indicates a l6-bit quantity or register. A symbol enclosed 
in parentheses in the machine operation section indicates 
that the value whose address is specified is used. The 
following 1S a summary of the notation used; exceptions will 
be noted where appropriate in the FOLTOw rng Sect Tone: 


r one of the 8—bit registers A, 3B, C, D, E, H, L 

n any 8-bit absolute value 

11 an index register reference, either X or Y 

d an 8-bit index displacement where -128 < d < 127 

zz 6B for the BC register pair, D for the DE pair 

nn any 16-bit value, absolute or relocatable 

rx B for the BC register pair, D for the DE pair, H for the 
HL pair, SP for the stack pointer 

qq 8 for the BC register pair, D for the DE pair, H for the 
HL pair, PSW for the A/Flag pair 

Ss any of r (defined above), M, or d(1i1) 

JFF interupt flip-flop : 

CY carry flip-flop 

ZF zero flag " 

tt B for the BC register pair, D for the DE pair, SP for 
the stack pointer, X for tndex register IX 

uu B for the BC register pair, D for the DE pair, SP for 
the stack pointer, Y for index register IY 

b a bit position in an 8-bit byte, where the bits are 
numbered from right to left QO to 7 | 

PC program counter 

vi(n]j bit n of the 8—bit value or register V 

v(n-m] bits n through m of the 8-bit value or register v | 

VV\H the most Significant byte of the 16-bit value or 
register vv | : 

vv\L the least significant byte of the 16-bit value or 
register vv ; ee bi 
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Jv an input operation on port v °* 

Ov an output operation on port v 

w<-v the value of w is replaced: by the value of v 
w<->v the value of w is exchanged with the value of v 


a 
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Mnemonic 


a 
we 7 ow 


8-Bit Load Group 


Operation 

r <- r' 

r <= (HL) : 
r <= (11i+d) 

(HL) <- x 

(litd) <- r 

r<- n 

(HL) <- n 

(litd) <- n 

A <~- (nn) 

(nn) <- A ? 
A <- (22) aes 
(zz) <- A —— 
A <- I 

A <- R 

I <- A 

R <-~ A 


NN NN RH RWW dN WR We Re 


# of Bytes 
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16-Bit Load Group 


' ae 


Mnemonic Operation aa # of Bytes 
LXI rr,nn re <- nn 3 
LXI ii,nn ji <- nn ‘ 4 
LBCD nn B <- (nntl1) 4 
C <- (nn) 
LDED nn D <- (nntl) 4 
E <- (nn) 
LHLD nn H <— (nntl) 3 
LL <= (nn) © 
LIXD nn IX\H <- (nntl) 4 
IX\L <- (nn) : 
LIYD nn ITY\H <- (nntl) --+ 4 
; IY\L <- (nn) eo 
LSPD nn SP\H <- (nnt+l) | 4 
SP\L <- (nn) 3 
SBCD nn (nn+l) <- B 4 
(nn) <- C | 
SDED nn (nn+l) <-— D : 4 
| (nn) <- E. | 
SHLD nn (mnt+l) <- H 3 
(nn) <- L 
SIXD nn (nnti) <= LA\H =. 7 4 
(nn) <- IX\L 
SIYD nn (nmntl) <- IY\H 4 
(mn) <- IY\L 
SSPD nn (nnt+l) <- SP\H - 4 
(nn) <- SP\L © 
SPHL SP <- Bl. 1 
SPIX SP <—- IX 2 
SPIY SP <- IY 2 
i 


PUSH gg (SP=1) <= qq\i= 
) (SP=2).. <= Gayl 

: SP <=(SP =. 2 | 
PUSH 11 (oPHl).. << “2aNee . 2 


(SP-2) <- ii\L 
SP <~ SP - 
POP qg aqg\H <- (SP+1). l 


qq\L <- (SP) 

SP <- SP + 2 | : 
POP iil sD \H <= (SP+1)>? 2 

1i\L <-— (SP) | | 

SP <- SP + 2 
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Exchange and Block Transfer And Search Group . 


ah asm eur Oe GEE aeP GER GER cute Gem GER CD ahem CD ahem Cm cee CE ee a ame ee ee CP CRF eee C8 ew ewe ce ee CoD ame ee am com Cm amt eum ame eum eee oh oD 


Mnemonic aches creat # of bytes 
XCHG HL <-> DE j 
EXAF. PSW <—> PSW' 1 
EXX BCDEHL <-> BCDEHL' 1 
XTHL H <-> (SP+1) | J 
L <-> (SP) 
XTIX IX\H <-> (SP#l1). 2 
IX\L <=> (SP) 
XTIY IY\H <-> (SPt1) © | 2 
IY\L <-> (SP) 


LDI : (DE) <— (HL) 2 
DE <- DE + 1 el 
HL <- HL + 1 
BC. <= BC =.2 
LDIR repeat LDI until BC= QO 2 
LDD (DE) <-— (HL) 2 
DE <- DE - l 
HL <- AL - 1 
BC <= BC — J 
LDDR | repeat LDD until BC=0 2 
CCI : A - (HL) 2 
HL <~ dL +1 
a ee & 5 (BCs <= BC = 1... eee 
CCIR repeat CCI until A=(HL) 2 


or BC=0 . 
CCD A — (HL) - 2 


HL <~ HL - 1 
BC <~ BC - l 
CCDR repeat CCD until A=(HL) 2 
or BC=0 : 
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8-Bit Arithmetic and Logical Group 
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Mnemonic Operation me - #-~of Bytes 


ADD r A <-~ A +r l 
ADD M A <~ A + (HL) l 
ADD d(ii) A <-~ A + (iitd) 3 
ADI n A <~ A +n 2 
ADC S ;i A <~ A + sg + CY. 

ACT n 

SUB S A <-~- A - Ss 

SUI n 

SBB S A <~ A- gs -— CY 

SBI n 

ANA S A <- A & 5 

ANI n 

ORA Ss A <- A ! s 

ORI n 

XRA Ss A<-A” gs 

XRI n | 

CMP S A - s 

CPI n | 

INR S s <- s +] 

DCR S s <-s-]l 


¢ 
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General Purpose Arithmetic and Control Group 


ue am «4 «2 asm eu ax co EP que? eee «ee ce am ee «= om Com ae ame emt ae am a eb ae ae 


DAA convert A to packed BCD | 1 
after an add or 
Subtract of packed BCD 


. operands | 
CMA A <- #A 1 
NEG A <- -A 2 
CMC CY <=- #CY 1 
STC CY <- l 1 
NOP no operation 1 
HLT halt | 1 
DI JEFF <- 0 i 
El IFF <- l ao 1 
IMO interrupt mode 0 2 
IM1l interrupt mode :l 2 
IM2 interrupt mode 2 2 


i 
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16-Bit Arithmetic Group 
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Mnemonic Operation # of Bytes - 
DAD rr HL <- HL + rer 1 

DADC rr HL <= HL + rr + CY 2 

DSBC rr HL <- HL - rr —- CY 2 

DADX tt IX <- IX + tt 2 

DADY uu TY <- IY + wu 2 

INX rr re <= rr+i 1 

INX 1i 11 <- li +1 2 

DCX rr rr <= rr -'l 1 

DCX 11 ii <- 11 - l 2 
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Ppeiccnline 
RLC 
RAL 
RRC 
RAR 
RLCR S 
RALR S 
RRCR S 
RARR S 
SLAR S 
SRAR S 
SRLR S 
RLD 
RRD 


Rotate and Shift Group 


ae en? @ae 82 Ge «a8 oe Ge ae 


Afnt+l] <- A[n] 
A{0} <- A[7] 
CY <- A[7 
Af[nt+l] <- Af[n] 
A[0] <- CY 

CY <- A[7] 
Afn] <- A[n+]1] 
A[7] <- A[0] 
CY <- A[0]} 
A{n] <- A{ntl] 
A[7] <- CY 

CY <- A[0] 
s{[ntl] <- s[n] 
s{0) <- s[{7] 
CY <- s[7J 
s{ntl] <- sf[n]} 
s{0}) <- CY 

CY <- s[7] 
s[n}) <- s[n+t+l} 
s{7] <- s[0]} 
CY <- s[{0Q)- 
s{[n]J <- s[ntl]} 
s{7) <- CY 

CY <- s[Q] 
s{nt+l] <- s[n]} 
s{QO] <- Q 

CY <- s[{7] 
s{n) <- s [n+l] 
s{7] <- s[7] 
CY <- s[{0] 
s{n}) <- s{[nt+l]} 
s{7J] <- 0 

cy <- s[0] 


A(0-3] <- (HL) [: 
<- (H 


(HE) (Osa) cen Oe 


-~ 
(HL) {4-7] 


a ia 


4-7 
L) | 
é 3 


O= 
3] 


(HL) (0-3) <- (HL) [4- 
(HL) [4-7] <- A[0-3] 


A[0-3] <- (HL) [0-3] 


7] 


2 (or 4) 
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Bit Set, Reset, and.,Test Group - 


Mnemonic Operation te # of Bytes” 


b,r ZF <- #r[b] 2 

b,M ZF <=- #(HL) [b] 2 
BIT b,d(11) ZF <—- #(11+d).[b 4 

b,s s{b] <- l | 

b,s s[b] <- Q 


, a6 
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Jump Group 
Mnemonic Operation | # of Bytes 
JMP nn PC <= nn 3 
JZ nn 1f zero, then JMP 3 
| else continue . 
JNZ nn | if not zero 3 
JC nn 1f carry 3 
JNC nn 1f not carry 3 
JPO nn 1f parity odd 3 
JPE nn if parity even 3 
JP nn if sign positive 3 
JM nn | if sign negative. 3. 
JO nn if overflow 3 
JNO nn | if not overflow 3 
JMPR nn PC <~ nn 7 | 2 
where -126 < nn-PC < 129 
 JRZ nn if zero, then JMPR | 2 
else continue 
JRNZ nn if not zero 2 
JRC nn 1f carry 2 
JRNC nn if not carry 2 
DJNZ nn B<- B - l | 2 
if B=0 then continue 
else JMPR 
PCHL PC. <= AL 1 
PCI X PC <- IX 2 
PCIY PC <- IY 2 
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Mnemonic 

CALL nn 
CZ nn 
CNZ nn 
CC nn 
CNC nn 
CPO nn 
CPE nn 
CP nn 
CM nn 
CO nn 
CNO nn 
RET 

RZ 

RNZ 

RC 

RNC 

RPO 

RPE 

RP 

RM 

RO 

RNO 

RETI 

-RETN 

RST n 


Call and Return Group 


ae gem a) cum eR ee ae Gh a8 am ae 688 O88 GP CP OR, GP EF a a om 


(SP-l1) <- PC\H 

(SP-2) <- PC\L 

SP <= SP - 2 : 

PC <- nn _ 

if zero, then CALL 
else continue 

if not zero 

if carry 

if not carry 

if parity odd 

if parity even 

1f sign positive» 

if sign negative 

1f overflow 

if not overflow’. 

PC\H <- (SP+l) 

PC\L <- (SP) 

SP <- SP + 2 

if zero, then RET 
else continue 

if not zero 

if carry 

if not carry 

if parity odd 

if parity even 

if sign positive 

if sign negative 

if overflow 

if no overflow 


return from interrupt 
return from non-maskable 


interrupt 
(SP-1) <- PC\H 
(SP-2) <-— PC\L 
PC <- 8 * n - 

where 0 <=n < 8 


eS eet ae at On eet ee ane Oe ase 


WW 


mm WW WW WW Ww W WW 


NO Ne ee ee 


~~ 
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Input and Output -Group 


eb GR ate A ca Ch CE CRD ae eam ee cu C8 CE em RP RR oo ae oem aD wee 


Mnemonic Operation oe # of Bytes 


IN n A <- In 2 
INP rc oy €=- I(C) 2 2 
INI (HL) <- I(C) 2 
| B<- B - 1 
bee HL <- HL + 1 
INIR repeat INI until B=0 2 
IND (HL) <- I(C) 2 
B<-B-l 
HL <- HL - 1 
INDR repeat ND until B=0 2 
OUT n On <- A er 2 
OUTP r O(C) <- r eee 2 
OUTI O(C) <- (HL) 2 
B<- B - 1 
HL <- HL + 1 
OUTIR repeat CJTI until B=0 2 
OUTD O(C) <- {HL) 2 
B<- B - 1 


HL <- HL - l 
OUTDR repeat OUTD until B=0 2 
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-ASCII dtextd | [n] ... 
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The .ASCII pseudo-op enters /-bit ASCII characters into 
the program. The text 1S either entered between two 
Gelimiters, Or aS a numeric value enclosed in square 


brackets ([]), and the two forms may-be intermixed and 


repeated as deSired. 


-ASCIS dtextd | [n] ... 


The .ASCIS pseudo-op enters 7-bit ASCII characters into 
the program, and flags the last character by setting 
its high-order bit on. The ‘format of the text is the 


Same as for the .ASCII pseudo-op. 


-ASCIZ dtextd | [n] ... 


The .ASCIZ pseudo-op enters 7-bit ASCII characters into 
the program, and flags the end of the characters by 
inserting an additional null byte. The format of the 


text is the same as for the .ASCII pseudo-op. 


-BLKB nn 


The .~.BLKB pseudo-op reserves a block of contiguous 


storage nn bytes long. 


~-BLKW nn 


The .~.BLKW pseudo-op reserves a block of contiguous 


storage nn words long (nn x 2 bytes). 


BX TE: Tr 45. Hr eae 


The .BYTE pseudo-op enters Single byte values into-.the 
program. Multiple values may be entered by Separating 


them with a comma. 


-DEFINE symbol [argl,arg2,...J=[text] 


The .DEFINE pseudo-op defines a macro with the name 
symbol. argl through argn are optional dummy 
arguments. The body of the macro is’ represented by 


text. 
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-END nn 


The .END pseudo-op signals the end of the assembly. 


When encountered during PASS l, it Simply returns to oa 


the initialization section. During a listing pass, it 
initlates the listing of the symbol table (if not 
previously suppressed by the .XSYM psSeudo-op). During 
a punch pass, i1t generates an EOF record on the hex 
tape containing the value nn.as the starting address of 
the object program. 


. ENTRY symboll {, symbol2 sg) 


The .ENTRY pseudo-op identifies the internally defined 
symbols which are subroutine library entry points to 
this program. Multiple symbols may be identified by 
Separating them with commas. a 


. “sy 


~-ERROR dtextd 


The ~ERROR pseudo-op causes an "*" error to occur, 
forcing the listing of the current line, and an error — 
notification. The delimited text is treated as a 
- REMARK. 


~EXIT 


The .EXIT pseudo-op causes an-immediate exit from the 
current macro expansion to occur. 


-EXTERN symboll {, symbol2 ...} 


The .EXTERN pseudo-op defines those symbols which are 
referenced in this program but are defined in another, 
separately assembled, program. Multiple symbols can be 
defined by separating them with commas. 


. 18080 
The .18080 pseudo-op enables the 2 warning message. 
This warning will be given whienever a machine operation 
unigue to the 280 iS encountered. 


-IDENT symbol 


The . IDENT pseudo-op gives the module a name for later 
use by the linkage editor. 
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.INTERN symboll {, symbol2 ...} ' 
The .INTERN pseudo-op identifies those symbols which 
are defined in this program and which will be 
referenced aS external symbols by some separately 
assembled program. Multiple-symbols may be identified 
by separating them with commas. 


- LADDR 


The .~LADDR pseudo-op changes the listing mode from 
displaying 16-bit quantities to displaying the 280 
image with the least Significant byte first. 


» LALL 


The .~.LALL pseudo-op causes the assembler to list every 
text character processed, including those suppressed in 
the normal listing. is 


~ LCTL 


The .~LCTL pseudo-op causes the assembler to list all 
listing control statements. : 


~ LINK 


The .LINK pseudo-op causes’ the assembler to output 
linkage information to the object file. 


~LIST 


The .LIST pseudo-op resumes a listing which has been 
stopped by the .XLIST pseudo-op. 


. LIMAGE 


The .LIMAGE pseudo-op changes the listing mode to 
display every byte of object code generated rather than 
the normal mode of a maximum of five bytes per. 
Statement. . 7 


~LOC nn 


The .~LOC pseudo-op changes the value of the assembler's 
program counter to nn. If nn is relocatable, then all 
labels will. be assigned relocatable values. If it 1s 
absolute, then absolute values will be assigned. 
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.LSYM - 


The .LSYM pseudo-op reenables the listing of the symbol 
table during the .END pseudo-op processing after it has 
been disabled by the -.XSYM. pseudo-op. The .LSYM 
pseudo-op must occur prior to the .END pseudo-op to be 
effective. 


-MASYN symboll,symbol2 


~ 


The .MASYN pseudo-op allows the definition of a new 
macro to be the Same as a previously defined one. 
Symbol2 is defined to be a macro identical to the one 
defined as symboll. 


~OPSYN symboll,symbol2 
The .OPSYN pseudo-op allows the... definition of a new op 
code mnemonic aS a Synonym of..an already existing one. 
The symboll must be a defined machine or pseudo op code 
(Or one previously defined using .OPSYN), symbol2 will 
be defined to be the Same operation. 


~PABS 


The .~PABS pseudo-op signals that the hex object tape 
produced from this point on in the assembly is to be in 
absolute (INTEL compatable) format. 

.PAGE | 


The .~PAGE pseudo-op causeS a Skip to the top of the 
next page during a listing pass. 


se BIN 


The .PBIN pseudo-op specifies that the object tape is 
to be produced in binary. | 


. PHEX 


The .PHEX pseudo-op specifies that the object tape is 
to be produced in ASCII. 


» PREL 


The .PREL pseudo- -op signals that the hex object tape 


produced from this point on in the aS Semory 1s to be in 


relocatable (TDL standard) format. 
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-PRNTX dtextd. - 


The .PRNTX pseudo-op will cause its text string to be 
printed on the console whenever it 1S encountered in. 
the assembly process. 7 | 


ew 


~~. PSYM 


The .PSYM pseudo-op Signals that the entire symbol 
table from the assembly is to be punched at the end of 
the object tape. The .PSYM pseudo-op must appear prior 
to the .~.END pseudo-op to be effective. 


~-RADIX n 


The .RADIX pseudo-op changes the default base in which 
a numeric constant is interpreted during the assembly. 
to n. The valid values for n are 2, 8, 10, or 16. The 
value is always interpreted as a decimal number. 


~-RAD40 symbol 


The .~.RAD40 pseudo-op generateS a unigue 4 byte value in 
radix-40 notation for the symbol given. The symbol 
must conform to the rules for any symbol in the 
assembly. This pseudo-op is used mostly for developing 
system software utilizing Symbol tables. 


~RELOC 


The .RELOC pseudo-op restores the value of the 
assembler's program counter. to whatever i1t was before 
the immediately preceding .LOC pseudo-op. 


»-REMARK dtextd 


The .~REMARK pseudo-op allows,the entry of multiple line 
comments into the source program. All of the text. 
between the delimiters is listed but is ignored. The |. 
text may contain carriage return/line feeds. ; we 


sRLLot 


The .~RLIST pseudo-op restores the listing control flags 
from the top element of the .SLIST push-down stack. 


- SALL 


The .SALL pseudo-op Suppresses all macro expansions on 
the assembly listing (normally all lines generating 
code are listed). ae | 
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-SBTTL dtextd 


The .SBTTL pseudo-op sets ‘the sub-title for the 
assembly listing to the specified text string (which 
must be less than 72 characters in length). If the 
-SBTTL pseudo-op is the first operation after a .PAGE, 
the sub-title will appear on the new page. 


~oLIST mi 


The .SLIST pseudo-op saves the current listing control 
flags on the top of a four element push-down stack. 


-SYN symboll,symbol2 


The .SYN pseudo-op makes any. two symbols synonymous. 
The symbol tables are searched for symboll in the 


normal operand field order.  (label/symbol, macro, 


opcode), and symbol2 is defined to have the same value 
as symboll. ms 


~SYSYN symboll,symbol2 


The .~.SYSYN pseudo-op makes one symbol the synonym of an 
already defined symbol/label. The value of 
symbol/label symboll is obtained, and symbol2 is 
defined to be the same type and value. 


-TITLE dtextd 


The .TITLE pseudo-op sets the title for the assembly 
listing to the specified text string (which must be 
less than 72 characters in length). The title is put 
at the top of every page during a listing. If the 
.TITLE pseudo-op is the first operation after a .PAGE 
pseudo-op, the title will be listed on the new page. 


~WORD nn {, nn ...} 


The .WORD pseudo-op enters 2-byte values into the 


program in proper 280 format (least significant byte 
first). Multiple values may by entered by Separating 
them with a comma. 


- ADDR 


Tne .XADDR pseudo-op is used after a .LADDR pseudo-op 
to return to the standard format of listing 16-bit . 
values. | | 
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" J XALL 


The .XALL pseudo-op is used after a .LALL or ~SALL. 
pseudo-op to return to the standard listing mode. 


.o”* 


-XCTL 


The .XCTL pseuod-op is used after a .LCTL pseudo-op to 
return the Standard mode of .suppressing the listing of 
listing control statements.” | 


.XIMAGE : aes 


The .~XIMAGE pseudo-op 1s used after a .LIMAGE pseudo-op 
to return to the standard listing mode of only five 
object bytes per statement. . 


~ALINK 


The .XLINK pseudo-op is used after a .~LINK pseudo-op to 
suppress the inclusion of linkage information in the. 
object file. 


~ALIST 


The .XLIST pseudo-op suppresses the listing of all 
following statements (until a -LIST pseudo-op is 
encountered). 


.XPSYM 


Tne .~.XPSYM pseudo-op disables the punching of the 
Symbol table at the end of the object tape after it has 
been enabled by the ~-PSYM pseudo-op. The .XPSYM 
pseudo-op must occur prior to the .END pseudo-op to be 
effective. 


-XSYM 


The .XSYM pseudo-op disables the listing of the symbol | 
table by the .END pseudo-op (unless reenabled by. the 


~-LSYM pseudo-op). The .XSYM pseudo-op must appear 
before the .END pseudo-op to be effective. 


- 280 
The .280 pseudo-op is used to disable the effect of a 


previous .18080 pseudo-op. This inhibits the Z warning 
message on machine operations unlque to the 280. | 
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arg,(true text] ... {[false text] } 


The .IFx pseudo-op will assemble the true text 
specified only 1f£ the particular condition being tested 
for is true, The optional false text is assembled if 
the condition is false. The .IFx pseudo-ops and their 
conditions are as follows: 


-IFl: assembling pass l ue 
-IF2: not assembling pass 1 
-IFB: blank | 

-IFDEF: defined _ 

-IFDIF: different 

-IFE: zero or blank 

-IFG: positive 

-IFGE: zero or positive 
-IFIDN: identical 

-IFL: negative 

-IFLE: zero or negative 
-IFN: not zero 

-IFNB: not blank 

~IFNDEF: not defined 
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Operation of the Assembler with a TDL Monitor 
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The TDL 280 Relocating Assembler is deSigned to operate 
with a TDL System Monitor. It relies upon the Monitor for 
all I/O and memory management _functions. (For further 
information on the TDL Monitors, consult the appropriate 
monitor reference manual.) When operating, the assembler 
will use all available memory for its various tables (all 
memory between the end of the assembler and the highest 
available memory location). No memory location below the 
assembler 1s changed by its operation. 


The first step in using the assembler is to load it into | 


the desired memory location using the monitor “R" command. 
After the load has been completed, if the monitor is not . 
located at the standard memory address (FOQQO hex), it will 
be necessary to change the assembler's monitor transfer 
vector to point to the monitor. This transfer vector 
consists of nine (9) JMP instructions located beginning at 
relative address six (6 hex) in the program. The addresses 
of these instructions should be modified to point to the 
correct locations. 

After the assembler is loaded and ready to operate, the 
appropriate monitor commands should’ be used to deSignate the 
reader, punch, and list devices as desired. The console 
device is also used during the assembly. After readying the 
source program in the reader, a "G" command should be used 
to start the assembler. 

It is important to note that.the assembler requires a 
"controlled" reader device (a’ ‘device which provides 
characters on demand, at whatever rate the program wants 
them). In the same manner in which the assembler “waits" 
for the next character from the reader, the reader must be 
capable of "waiting" for the next .demand from the assembler. 
(For further information on converting a non-controlled 


reader to a controlled one, see one of the TDL System 


Monitor reference manuals.) | 

When first started (and whenever an assembly pass is 
completed), the assembler asks "“PASS=" on the console. 
Valid responses to this are only the numbers from 0 to 8. A 
response of 0 will return to the monitor, but ina manner 
which will allow resumption of the assembly by reentering 
the "G" command.. The values 1.through 4 £42Signify which 
assembler pass is desired, as follows: 


1 Signifies the first assembly pass. The source is read, 
and all necessary tables are built.. 
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2 Signifies the listing only pass. The source is re-read, 
and a listing of the assembled program i1SsS.produced on. 
the list device. 7 

3 signifies the punch only pass. The source 1S re-read, 
and an object tape of the assembled program 1S produced . 
on the punch device. | 


4 signifies the combination of ‘passes 2 and 3. 


The values of 5 through 8 provide the same options as l 
through 4, but do not reinitialize the assembler in any way 
before proceeding. This allows the assembly of a program 
residing on more than one source tape. Each of the pieces 
must, however, be terminated by its own .~.END pseudo-op. | 

During the first assembly pass.) (pass l), it 1S possible 
that some error messages will be output on the list device. 
These errors will be those uniquely determined during the 
pass. 

During the punch only pass (pass 3), no error mesSages. 
Will be listed, but an errors indication will be given on 
the console at the end of the assembly. : 

While an assembly is taking place, a number of console 
control options are available. A control-C will always trap 
back to the monitor after the completion of the current 
Statement. The assembly may be resumed (if no registers 
have been changed) by using the monitor “G”" command. A 
control-C will, however, result in monitor output on the 
console device, which could spoil a listing i1f£ the console 
is the list device. To avoid this, the use of a control-sS 
will temporarily halt the assembly (e.g. to put more paper 
in the teletype), but will not return to the monitor or 
cause any spurious output on the console device. A 
control-Q will resume the assembly. If a control-C is 
entered after the control-S, a trap to the monitor will 
occur as above. In addition, a control-T may be used to 
stop the assembly at the top of the next output page of the 
listing. When the control-T is entered on the keyboard, 
nothing will happen until the top-of-page 1s reached, at ~ 
which time the assembler will act as if a control-S had been 
entered (see above). All of the above features will, 
however, be disabled if the reader device is specified as. 
the Teletype. | 

When starting a listing vass, the paper in the. list 
device should be positioned at the top line of a page. The 
assembler will count lines and put a page number and heading 
at the top of every page. The page width is determined by 
the assigned list device. If the list device is the 
teletype (AL=T), then the page 1S assumed to be 72 
characters wide. If not, then it 1S assumed to be 80 
characters wide. In either case, it 1S assumed to. be 66 
lines long, and a two line margin 1s left at the top and the 
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Error Codes .. 


Errors in the source program encountered during the 
assembly process are indicated on the listing by a single 
letter code at the left of the statement in error. Although 
the assembler may detect more than two errors per statement, 
only the first two codes are given. As an added aid to 
locating the error in the statement, a question mark is 
printed to the right of the character which triggered the 
error. All errors generate a question mark, even if they 
are not one of the first two per statement. 

The following is alist of the error codes and their 
meanings: 


A Argument error. This is a broad class of errors which 
may be caused by many different things. 


B Bad macro error. Either an error ina macro definition 
or a call on a bad macro. 


D. Duplicate symbol reference error. The symbol flagged is 
multiply-defined. The first value given to the symbol 
is used in the assembly. ‘ 


E External symbol error. An external symbol is improperly 
used in the statement. a | 


I Internal symbol error. An internal symbol 1S improperly 
used in the statement. | 


L Label error. An invalid character has been Foun in the 
label field of the statement. 


M Multiply-defined symbol error. A symbol is defined more 
than once. This error 1S given mostly during Pass 1. 
During the other passes, it usually will appear asa 
phase error (P). | | 


* 


O Operation error. The symbol in the operation field is 
not a valid machine operation code, macro name, or 
symbol. | 


P Phase error. A label 1S asSigned a value during Pass 2 
(or 3 or 4) which is different than that assigned during 
Pass l. 


Q Questionable error. This 1S a broad class of warnings 
wnich the assembler gives when it finds ambiguous 
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statements. Q errors may or may not generate correct 


code. The assembler will attempt to do what the 
programmer intended. 7 


R Relocation error. A eSieatabie: symbol or expression is 
incorrectly used (eg. in a .BLKB pseudo-op). 


T Table overflow. One of the Assembler’s internal tables 
has overflowed. The Assembler will attempt to continue, 
but no new labels or macros will be defined. 


U Undefined label/symbol error. A symbolic reference - 
which was never defined is used in the statement. 


X Index error. Another character appears in a Statement | 
| at a point where only an index register reference is 
allowed (X or Y). | 7 


Z Z80 error. A 280 machine operation has been Baeeunceres 
while in 8080 mode (.18080). .This is only a warning and. 
the opcode will be properly assembled. 


* User defined macro error. A ~-ERROR pseudo-op was 
encountered. | 
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The TDL Assembler produces two different object tape formats 
depending on the use of the .PABS.and the .PREL pseudo-ops. 
It also punches the two formats two different ways, binary 
(.PBIN) and ASCII (.PHEX). Each of the two formats will be 
described separately, and where differences between binary 
and ASCII exist, they will be .noted. In addition, the 
-XLINK option allows the suppression of some of the. 
information in the relocatable format to allow the direct 
production of a relocatable core image module instead of a 
relocatable object module. oe 


ae. 


TDL Object Module Format Definition. 


The use of the .PREL pseudo-op (which is default if neither 
is specified) causes the generation of the TDL Object Module 
Format. This format allows for simple relocation of 
complete programs by the TDL System Monitors, and for 
complex relocation and linking of modules by the TDL Linkage 
Editor. 


The default object module format 1s an extension of the 
INTEL “hex file" format, but 1S not compatible with that 
format. The module consists of a-sequential file of ASCII 
characters representing the binary data, symbol, and control 
information required to construct a final program from the 
module. All binary bytes within this Structure are 
represented as two ASCII characters corresponding to the 
hexadecimal value of the byte (e.g. 11001001 -> C9). All 
ASCII values are represented by the corresponding ASCII 
character (e.g. A -> A). In the binary punch mode,- the 
format is basically the same, but all binary bytes are 
represented by themselves, not as .two ASCII characters. 


Each of the different records within the module 1s indicated 
by the use of a prompt character as the first character of © 
the record (in the INTEL format, this is the ":"). ‘The 
valid prompt characters are: 


-> module identification record 

-> entry point record 

-> internal symbol record . . 

-> external symbol/relocation base record 
-> symbol table record 

-> data/program/end-of-file record 


se OM” tt @M m= 
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(Note that only the records prompted by a ; are output if — 
the .XLINK mode is in effect.) : [a 2 


Every record in the module is terminated by a one byte _ 
binary checksum of all of the preceeding bytes in the record 
except for the prompt character. The checksum is the two's 
complement of the sum of the preceeding bytes. Any output 
format (two character binary, one character ASCII or one 
byte binary) still countsS as only one byte in the checksum 
(1.e. before conversion for output). 


In addition, each record in the ASCII punch mode is 

preceeded by a carriage return/line feed sequence to 
facilitate listing the module on an external device. It is 
not present in the binary punch mode. 


The following descriptions are specified assuming ASCII 
punch mode. With the above noted .exception of the carriage 
return/line feed preceeding each record, the binary format 
1S identical, with each binary byte being left unexpanded. 
ASCII characters are left as they are in either mode. 


Module Identification Record (!) 


out ewe cu en a aun oe ae ae® eee a ee wee eee ee eee CEP ese aa ane ob ae ae a a we Se am amp 


Byte 1-2 CR/LF 
3 Exclamation voint (!) ‘prompt. 
4-9 ASCII module name. 


10-11 Checksum. 


Entry Point Record (@) 


CRE Cee SES eee oN ES euecy tee nee ce Onn mae eae ene at aa Ce exe ne 


Byte 1-2 CR/LF 
3 At-sign (@) prompt. 
4-5 Number of entry points in this record. | 
6-?? ASCII names of entry points, 6 bytes per name. 
The names are left justified and blank filled. 
2? Checksum 


Internal Symbol Record (#) 


Byte 1-2 CR/LF 
3 ~ Pound sign (#) prompt. 
4-5 Number of internal symbols in this record. | 
6-11 ASCII name of internal symbol, left justified 
and blank filled. — 


(12-13. Relocation base for symbol. The value of this ~~ 
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symbol is relative to the relocation base. 
specified. 7 | | 
Symbol value (16 bit). : : 
The above three fields. are repeated for each 


internal symbol in the record. 


Checksum. 


External Symbol/Relocation Base Record (\) 


14-17 


e@e868%hl68 
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CR/LF 

Back-slash (\) prompt. - 
Number of external/relocation symbols in this 
record. | | 
ASCII name of the symbol, left justified and 
blank filled. an | | | 
Relocation number assigned to this symbol in 


this module. This number is unique’ for each 


symbol. It starts with one and increases 
sequentially for each Subsequent 


external/relocation base symbol. 


Relocation segment size/external reference flag. 
If this value is zero, it represents a reference 
to a symbol defined externally to this module 
(usually a Subroutine or global data item). If 
it 1S non-zero, then'the value is the size of — 
the relocation segment as defined in this object 


module. This segment can contain either code or . 


data, and may be located anywhere in memory by 
the linkage editor, independent of any other - 
segment. « > 
The above three fields are repeated for each | 
symbol contained in this record. » 4 
Checksum. 


Symbol Table Record (&) 


> get ant eb ce ae oo «ah een ame 


~—, om a eee oon ame ae ne aah eam 


CR/LF . 
Ampersand (&) prompt. 
The remainder of this record is identical to the _ 
internal symbol record. All symbols defined in - 
this module are contained in these records. | 


Data/Program Record (;) 


ae en ant ape a «ee ab aw we om am 


Byte 1-2. 
3 


—_ ee ga are ere ame ark wae arm ome 


CR/LF- 


Semicolon (;) prompt 
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specified relocation base. This address is 
optionally generated See the language processor, 
and may be zero. | a | | 
10-11 Relocation base for Starting address. (In - 
-XLINK mode may be only “0 Or J: 6) . 
12-13 Checksum. 


INTEL Object Format 


The use of the .PABS pseudo-op causes an INTEL "hex" object 
module to be produced. This object tape can also be loaded 
by the TDL System Monitors, but provides no relocatability. 


All of the above comments concerning byte formats’) and 
checksums apply to this format as well. 


Byte 1-2 CR/LF 
3. Colon (:) prompt. > 
4-5 Number of binary data by és in this record. The 


maximum number 1s 32 binary bytes (64 bytes of 
ASCII representation). If this value is zero, 
this record is an end-of-file record, and the - 
load address is the program Starting address. 
6-9 Load address of the data in this record. 
10-11 Unused. 
12-?? Data bytes. 
2? Checksum. 
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Appendix G 


Aecenbiek Operation with CP/M 
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The TDL 280 Relocating/Linking Assembler is initiated by 
the CP/M command: 


ASM {sd:}file{.ext} {dd: | {switches} 


where 


sd is the optional CP/M disk specification for the 
source file (defaults to the logged in disk) 7 

file is the source file name | 

ext is the optional source file extension (defaults to . 
ASM) | oe | | 

dd is the optional CP/M disk specification for the 

| output files (defaults to the same as the source 
file) : | | 

switches are the optional assembly control switches, 
each of which 1s ae single letter and which may 
appear in any order (with no intervening spaces) 


The object file created by the assembly will have the same 
name as the source file, with an extension of .HEX if the 

_.PABS option was used, and .REL if the .PREL option was used 
(the default). en _ is Bead | 


Switches 
A ~-LALL | | 
B listing to both disk and list device 
C - LCTL 
D listing to disk (file name Same aS source with extension 
of PRN) : 

-PHEX (CP/M Aeeorie is .PBIN) 

. LIMAGE | 

_XLINK (CP/M default is .LINK) 

listing only - no object file*generated 
— object only - no listing eoucnauee 
~ .~PSYM 

-SALL 
~-ALIST 
- ASYM 


WKN DWOD RHE 


Note that all switches with pseudo-op equivalents will be 
overridden by contrary pseudo-ops within the source program. — 
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PS) 


‘Assembly Time Control 

All of the assembly time control options (ctl-C, ctl-S, i 
ctl-T) and page width options described in Appendix C also - 
apply to the CP/M based version. ‘-* 


